<?xml version="1.0" encoding="UTF-8"?>
<html filename="docs/SAX/IBaseXMLReader.html">
<body>
<a id="#top"/>
<h1>
	                Interface Summary : IBaseXMLReader </h1> Interface for reading an XML document using callbacks.

 <blockquote>
 <em>This module, both source code and documentation, is in the
 Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
 </blockquote>

 <p>XMLReader is the interface that an XML parser's SAX2 driver must
 implement.  This interface allows an application to set and
 query features and properties in the parser, to register
 event handlers for document processing, and to initiate
 a document parse.</p>

 <p>The XMLReader interface is split into a common base interface,
 IBaseXMLReader, and the actual IXMLReader specification which derives
 from it. This is done to improve type safety for applications which can
 handle both, standard and buffered XMLReader implementations (see BSAX.pas).
 Most applications need not be aware of this split definition.</p>

 <p>All SAX interfaces are assumed to be synchronous: the
 <a href="../SAX/IXMLReader.html#parse">parse</a> methods must not return until parsing
 is complete, and readers must wait for an event-handler callback
 to return before reporting the next event.</p>

 <p>This interface replaces the (now deprecated) SAX 1.0
 <a href="../SAX/IParser.html">Parser</a> interface.  The XMLReader interface
 contains two important enhancements over the old Parser
 interface (as well as some minor ones):</p>

 <ol>
 <li>it adds a standard way to query and set features and
  properties; and</li>
 <li>it adds Namespace support, which is required for many
  higher-level XML standards.</li>
 </ol>

 <p>There are adapters available to convert a SAX1 Parser to
 a SAX2 XMLReader and vice-versa.</p>

<br/><b>Since : </b> SAX 2.0
<br/><b>See : </b> <a href="../SAX/IXMLFilter.html">IXMLFilter</a>
<h2>
	              Methods
	            </h2>
<div style="padding-left:10px">
<a href="#getFeature">
	                  function
	                 getFeature(SAXString) : Boolean</a>
<br/>
<a href="#setFeature">
	                  procedure
	                 setFeature(SAXString, Boolean)</a>
<br/>
<a href="#getProperty">
	                  function
	                 getProperty(SAXString) : IProperty</a>
<br/>
<a href="#setErrorHandler">
	                  procedure
	                 setErrorHandler(IErrorHandler)</a>
<br/>
<a href="#getErrorHandler">
	                  function
	                 getErrorHandler() : IErrorHandler</a>
<br/>
<a href="#setEntityResolver">
	                  procedure
	                 setEntityResolver(IEntityResolver)</a>
<br/>
<a href="#getEntityResolver">
	                  function
	                 getEntityResolver() : IEntityResolver</a>
<br/>
<a href="#parse">
	                  procedure
	                 parse(IInputSource)</a>
<br/>
<a href="#parse">
	                  procedure
	                 parse(SAXString)</a>
<br/>
</div>
<br/>
<h2>
	                Properties
	              </h2>
<div style="padding-left:10px"/>
<br/>
<hr width="100%"/>
<a name="#getFeature">
<p>
<b>function</b> getFeature(<b>const</b> name : SAXString) : Boolean; </p>
</a> Look up the value of a feature flag.

 <p>The feature name is any fully-qualified URI.  It is
 possible for an XMLReader to recognize a feature name but
 temporarily be unable to return its value.
 Some feature values may be available only in specific
 contexts, such as before, during, or after a parse.
 Also, some feature values may not be programmatically accessible.
 (In the case of an adapter for SAX1 <a href="../SAX/IParser.html">IParser</a>, there is no
 implementation-independent way to expose whether the underlying
 parser is performing validation, expanding external entities,
 and so forth.) </p>

 <p>All XMLReaders are required to recognize the
 http://xml.org/sax/features/namespaces and the
 http://xml.org/sax/features/namespace-prefixes feature names.</p>

 <p>Some feature values may be available only in specific
 contexts, such as before, during, or after a parse.</p>

 <p>Typical usage is something like this:</p>

 <pre>
 var
   r : IXMLReader;
 begin
   r:= TMySAXDriver.Create() as IXMLReader;

   // try to activate validation
   try
     r.setFeature('http://xml.org/sax/features/validation', true);
   except
     on e : ESAXException do
     begin
       Showmessage('Cannot activate validation.');
     end;
   end;

   // register event handlers
   r.setContentHandler(TMyContentHandler.Create() as IContentHandler);
   r.setErrorHandler(TMyErrorHandler.Create() as IErrorHandler);

   // parse the first document
   try
     r.parse('file://c:/mydoc.xml');
   except
     on e : ESAXException do
     begin
       Showmessage('XML exception reading document.');
     end;
     on e : Exception do
     begin
       Showmessage('Exception reading document.');
     end;
   end;
 </pre>

 <p>Implementors are free (and encouraged) to invent their own features,
 using names built on their own URIs.</p>

<br/><b>Parameter : </b> name The feature name, which is a fully-qualified URI.
<br/><b>Result : </b> The current value of the feature (true or false).
<br/><b>Exception : </b> ESAXNotRecognizedException If the feature
            value can't be assigned or retrieved.
<br/><b>Exception : </b> ESAXNotSupportedException When the
            XMLReader recognizes the feature name but
            cannot determine its value at this time.
<br/><b>See : </b> <a href="../SAX/IXMLReader.html#setFeature">IXMLReader.setFeature</a>
<br/>
<p>
<a href="#top">Top</a>
</p>
<hr width="100%"/>
<a name="#setFeature">
<p>
<b>procedure</b> setFeature(<b>const</b> name : SAXString;  value : Boolean); </p>
</a> Set the value of a feature flag.

 <p>The feature name is any fully-qualified URI.  It is
 possible for an XMLReader to expose a feature value but
 to be unable to change the current value.
 Some feature values may be immutable or mutable only
 in specific contexts, such as before, during, or after
 a parse.</p>

 <p>All XMLReaders are required to support setting
 http://xml.org/sax/features/namespaces to true and
 http://xml.org/sax/features/namespace-prefixes to false.</p>

<br/><b>Parameter : </b> name The feature name, which is a fully-qualified URI.
<br/><b>Parameter : </b> state The requested value of the feature (true or false).
<br/><b>Exception : </b> ESAXNotRecognizedException If the feature
            value can't be assigned or retrieved.
<br/><b>Exception : </b> ESAXNotSupportedException When the
            XMLReader recognizes the feature name but
            cannot set the requested value.
<br/><b>See : </b> <a href="../SAX/IXMLReader.html#getFeature">IXMLReader.getFeature</a>
<br/>
<p>
<a href="#top">Top</a>
</p>
<hr width="100%"/>
<a name="#getProperty">
<p>
<b>function</b> getProperty(<b>const</b> name : SAXString) : IProperty; </p>
</a> Look up the value of a property.

 <p>The property name is any fully-qualified URI.  It is
 possible for an XMLReader to recognize a property name but
 temporarily be unable to return its value
 Some property values may be available only in specific
 contexts, such as before, during, or after a parse.</p>

 <p>XMLReaders are not required to recognize any specific
 property names, though an initial core set is documented for
 SAX2.</p>

 <p>Implementors are free (and encouraged) to invent their own properties,
 using names built on their own URIs.</p>

 <p> Within SAX for Pascal property setting is handled through
 the interface that is returned by the call to getProperty. This
 eliminates the need for multiple lookups in tight loop situations
 as a user can maintain a reference to the interface.</p>

<br/><b>Parameter : </b> name The property name, which is a fully-qualified URI.
<br/><b>Result : </b>s An Interface that allows the getting and setting of the property
<br/><b>Exception : </b> ESAXNotRecognizedException If the property
            interface cannot be retrieved.
<br/><b>Exception : </b> ESAXNotSupportedException When the
            XMLReader recognizes the property name but
            cannot determine its interface value at this time.
<br/>
<p>
<a href="#top">Top</a>
</p>
<hr width="100%"/>
<a name="#setErrorHandler">
<p>
<b>procedure</b> setErrorHandler(<b>const</b> handler : IErrorHandler); </p>
</a> Allow an application to register an error event handler.

 <p>If the application does not register an error handler, all
 error events reported by the SAX parser will be silently
 ignored; however, normal processing may not continue.  It is
 highly recommended that all SAX applications implement an
 error handler to avoid unexpected bugs.</p>

 <p>Applications may register a new or different handler in the
 middle of a parse, and the SAX parser must begin using the new
 handler immediately.</p>

<br/><b>Parameter : </b> handler The error handler.
<br/><b>See : </b> <a href="../SAX/IXMLReader.html#getErrorHandler">IXMLReader.getErrorHandler</a>
<br/>
<p>
<a href="#top">Top</a>
</p>
<hr width="100%"/>
<a name="#getErrorHandler">
<p>
<b>function</b> getErrorHandler() : IErrorHandler; </p>
</a> Return the current error handler.

<br/><b>Result : </b> The current error handler, or nil if none
         has been registered.
<br/><b>See : </b> <a href="../SAX/IXMLReader.html#setErrorHandler">IXMLReader.setErrorHandler</a>
<br/>
<p>
<a href="#top">Top</a>
</p>
<hr width="100%"/>
<a name="#setEntityResolver">
<p>
<b>procedure</b> setEntityResolver(<b>const</b> resolver : IEntityResolver); </p>
</a> Allow an application to register an entity resolver.

 <p>If the application does not register an entity resolver,
 the XMLReader will perform its own default resolution.</p>

 <p>Applications may register a new or different resolver in the
 middle of a parse, and the SAX parser must begin using the new
 resolver immediately.</p>

<br/><b>Parameter : </b> resolver The entity resolver.
<br/><b>See : </b> <a href="../SAX/IXMLReader.html#getEntityResolver">IXMLReader.getEntityResolver</a>
<br/>
<p>
<a href="#top">Top</a>
</p>
<hr width="100%"/>
<a name="#getEntityResolver">
<p>
<b>function</b> getEntityResolver() : IEntityResolver; </p>
</a> Return the current entity resolver.

<br/><b>Result : </b> The current entity resolver, or nil if none
         has been registered.
<br/><b>See : </b> <a href="../SAX/IXMLReader.html#setEntityResolver">IXMLReader.setEntityResolver</a>
<br/>
<p>
<a href="#top">Top</a>
</p>
<hr width="100%"/>
<a name="#parse">
<p>
<b>procedure</b> parse(<b>const</b> input : IInputSource); </p>
</a> Parse an XML document.

 <p>The application can use this method to instruct the XML
 reader to begin parsing an XML document from any valid input
 source (a character stream, a byte stream, or a URI).</p>

 <p>Applications may not invoke this method while a parse is in
 progress (they should create a new XMLReader instead for each
 nested XML document).  Once a parse is complete, an
 application may reuse the same XMLReader object, possibly with a
 different input source.
 Configuration of the XMLReader object (such as handler bindings and
 values established for feature flags and properties) is unchanged
 by completion of a parse, unless the definition of that aspect of
 the configuration explicitly specifies other behavior.
 (For example, feature flags or properties exposing
 characteristics of the document being parsed.)
 </p>

 <p>During the parse, the XMLReader will provide information
 about the XML document through the registered event
 handlers.</p>

 <p>This method is synchronous: it will not return until parsing
 has ended.  If a client application wants to terminate
 parsing early, it should throw an exception.</p>

<br/><b>Parameter : </b> source The input source for the top-level of the
        XML document.
<br/><b>Exception : </b> ESAXException Any SAX exception.
<br/><b>Exception : </b> Exception An IO exception from the parser,
            possibly from a byte stream
            supplied by the application.
<br/><b>See : </b> <a href="../SAX/TInputSource.html">TInputSource</a>
<br/><b>See : </b> <a href="../SAX/IXMLReader.html#parse.SAXString">IXMLReader.parse(SAXString)</a>
<br/><b>See : </b> <a href="../SAX/IXMLReader.html#setEntityResolver">IXMLReader.setEntityResolver</a>
<br/><b>See : </b> <a href="../SAX/IXMLReader.html#setDTDHandler">IXMLReader.setDTDHandler</a>
<br/><b>See : </b> <a href="../SAX/IXMLReader.html#setContentHandler">IXMLReader.setContentHandler</a>
<br/><b>See : </b> <a href="../SAX/IXMLReader.html#setErrorHandler">IXMLReader.setErrorHandler</a>
<br/>
<p>
<a href="#top">Top</a>
</p>
<hr width="100%"/>
<a name="#parse">
<p>
<b>procedure</b> parse(<b>const</b> systemId : SAXString); </p>
</a> Parse an XML document from a system identifier (URI).

 <p>This method is a shortcut for the common case of reading a
 document from a system identifier.  It is the exact
 equivalent of the following:</p>

 <pre>
 input:= TInputSource.Create(systemId) as IInputSource;
 try
   parse(input);
 finally
   input:= nil;
 end;
 </pre>

 <p>If the system identifier is a URL, it must be fully resolved
 by the application before it is passed to the parser.</p>

<br/><b>Parameter : </b> systemId The system identifier (URI).
<br/><b>Exception : </b> ESAXException Any SAX exception.
<br/><b>Exception : </b> Exception An IO exception from the parser,
            possibly from a byte stream
            supplied by the application.
<br/><b>See : </b> <a href="../SAX/IXMLReader.html#parse.TInputSource">IXMLReader.parse(TInputSource)</a>
<br/>
<p>
<a href="#top">Top</a>
</p>
<div style="padding-left:10px">
<hr width="100%"/>
<a name="#ErrorHandler">
<p> <b>ErrorHandler</b>
</p>
</a> Extension property to get and set the ErrorHandler

<br/><b>Result : </b> The current Error handler, or nil if none
         has been registered.
<br/><b>See : </b> <a href="../SAX/IXMLReader.html#getErrorHandler">IXMLReader.getErrorHandler</a>
<br/><b>See : </b> <a href="../SAX/IXMLReader.html#setErrorHandler">IXMLReader.setErrorHandler</a>
<br/>
<p style="margin-left:30px">
<code>property ErrorHandler: IErrorHandler
      read getErrorHandler write setErrorHandler</code>
</p>
<p>
<a href="#top">Top</a>
</p>
<hr width="100%"/>
<a name="#EntityResolver">
<p> <b>EntityResolver</b>
</p>
</a> Extension property to get and set the EntityResolver

<br/><b>Result : </b> The current content handler, or nil if none
         has been registered.
<br/><b>See : </b> <a href="../SAX/IXMLReader.html#getEntityResolver">IXMLReader.getEntityResolver</a>
<br/><b>See : </b> <a href="../SAX/IXMLReader.html#setEntityResolver">IXMLReader.setEntityResolver</a>
<br/>
<p style="margin-left:30px">
<code>property EntityResolver: IEntityResolver
      read getEntityResolver write setEntityResolver</code>
</p>
<p>
<a href="#top">Top</a>
</p>
<hr width="100%"/>
<a name="#Features">
<p> <b>Features</b>
</p>
</a> Extension property to get and set the IXMLReader's features

 @index name The feature name, which is a fully-qualified URI.
<br/><b>Exception : </b> ESAXNotRecognizedException When the
            XMLReader does not recognize the feature name.
<br/><b>Exception : </b> ESAXNotSupportedException When the
            XMLReader recognizes the feature name but
            cannot set the requested value.
<br/><b>Result : </b> The state of the feature (true or false)
<br/><b>See : </b> <a href="../SAX/IXMLReader.html#getFeature">IXMLReader.getFeature</a>
<br/><b>See : </b> <a href="../SAX/IXMLReader.html#setFeature">IXMLReader.setFeature</a>
<br/>
<p style="margin-left:30px">
<code>property Features[const name: SAXString]: Boolean
      read getFeature write setFeature</code>
</p>
<p>
<a href="#top">Top</a>
</p>
<hr width="100%"/>
<a name="#Properties">
<p> <b>Properties</b>
</p>
</a> Extension property to get the IXMLReader's property interfaces

 @index name The property name, which is a fully-qualified URI.
<br/><b>Exception : </b> ESAXNotRecognizedException When the
            XMLReader does not recognize the property name.
<br/><b>Exception : </b> ESAXNotSupportedException When the
            XMLReader recognizes the property name but
            cannot set the requested value.
<br/><b>Result : </b> The value stored in the property as an IProperty interface
<br/><b>See : </b> <a href="../SAX/IXMLReader.html#getProperty">IXMLReader.getProperty</a>
<br/>
<p style="margin-left:30px">
<code>property Properties[const name: SAXString]: IProperty
      read getProperty</code>
</p>
<p>
<a href="#top">Top</a>
</p>
</div>
<br/>
</body>
</html>